Fixes #5652

Summary

Closes a latent defect in SkillToolset that lets the LLM enter an unbounded retry loop when load_skill_resource returns RESOURCE_NOT_FOUND. Because the only existing backstop is RunConfig.max_llm_calls (default 500), a hallucinated path can quietly burn the entire per-invocation call budget before the framework intervenes — and max_llm_calls is a global cap on legitimate reasoning, not a defense against this specific failure mode.

This fix adds invocation-scoped termination to the tool itself, plus a complementary system-prompt rule, so the framework no longer relies on a perfect upstream prompt to avoid unbounded loops on a known error path.

Why this matters

This is a structural problem, not an edge case:

• The L2 load_skill response intentionally omits a manifest of available files — that is the agentskills.io progressive-disclosure contract, and it is correct for token economy. But it means the LLM must infer paths from prose instructions inside SKILL.md. Inferred paths are routinely wrong, even with strong models.
• RESOURCE_NOT_FOUND is returned as a structured soft string. From the model's perspective it looks transient and recoverable, exactly like a flaky network error — so it retries. There is no terminal signal in the current implementation.
• The LLM hallucinates a different path on every retry. In live testing the model never repeated the same path twice — it generated a new plausible variant each time. A per-path guard is therefore insufficient; the termination must be invocation-wide.
• Nothing in SkillToolset distinguishes "first miss" from "500th miss". The loop terminates only when max_llm_calls (default 500) is hit.
• Confounding scope ambiguity: the default system prompt does not draw a boundary between skill-bundled files (the legitimate target of load_skill_resource) and runtime user inputs (e.g., a PDF the user is processing). A model asked to analyze a runtime document will sometimes route it through load_skill_resource, hit RESOURCE_NOT_FOUND, and loop — even though the file was never a skill resource.

Live trace evidence

Captured via GET /debug/trace/session/{session_id} against adk web with a patched build:

SPAN: execute_tool load_skill_resource
  args:       {'file_path': 'references/reference_doc.md', 'skill_name': 'document-classifier'}
  error_code: RESOURCE_NOT_FOUND
  error:      Resource 'references/reference_doc.md' not found in skill 'document-classifier'.

SPAN: execute_tool load_skill_resource
  args:       {'skill_name': 'document-classifier', 'file_path': 'references/Document1.md'}
  error_code: RESOURCE_NOT_FOUND_FATAL
  error:      Resource 'references/Document1.md' not found in skill 'document-classifier'.
              This is resource lookup failure #2 this invocation. Do not retry any path
              — report the error to the user and stop.

The model tried references/reference_doc.md first, then hallucinated a completely different path (references/Document1.md) on the retry. The counter-based guard caught the second failure and returned RESOURCE_NOT_FOUND_FATAL, terminating the loop. A per-path guard would have missed this entirely.

What changed

Two layers in one file (src/google/adk/tools/skill_toolset.py), plus tests:

1. Code: invocation-scoped failure counter in LoadSkillResourceTool.run_async

A total RESOURCE_NOT_FOUND count (across all paths) is tracked on tool_context.state under the key:

temp:_adk_skill_resource_not_found_count_<invocation_id>

• The temp: prefix uses ADK's existing convention so the value is trimmed from the persisted event delta and never reaches durable session storage.
• The <invocation_id> suffix ensures correctness on in-memory session backends, where temp: keys are added to session.state and are not auto-cleared between invocations. Without the suffix, a failure in invocation A would spuriously escalate the first attempt in invocation B.

Behavior:

• First RESOURCE_NOT_FOUND within an invocation (any path) → returns RESOURCE_NOT_FOUND (unchanged).
• Any subsequent RESOURCE_NOT_FOUND within the same invocation → returns the new RESOURCE_NOT_FOUND_FATAL error code with an explicit "do not retry — report the error and stop" message. The counter includes the failure number so the LLM has unambiguous context.

The guard is invocation-scoped, path-agnostic (catches hallucinated variants), and adds no overhead on the success path.

2. Prompt: two additions to _DEFAULT_SKILL_SYSTEM_INSTRUCTION

• No-retry rule: "If load_skill_resource returns any error, do not retry the same path. Report the error to the user and stop."
• Scope boundary added to rule 3: clarifies that load_skill_resource is only for skill-bundled files in references/, assets/, or scripts/ — not for runtime user input. This addresses the secondary failure mode where the model confuses a runtime document with a skill resource.

Why both layers

Defense-in-depth. Code-only termination produces confusing downstream behavior when the LLM has no semantic reason to stop. Prompt-only termination relies on the LLM following the rule, which imperfect upstream prompts can override. Together they are robust.

Considered and rejected

Test plan

New tests in tests/unittests/tools/test_skill_toolset.py:

• test_load_resource_repeated_failure_escalates_to_fatal — second call on the same missing path within an invocation returns RESOURCE_NOT_FOUND_FATAL.
• test_load_resource_different_path_also_escalates_to_fatal — second call on a different missing path also returns RESOURCE_NOT_FOUND_FATAL; proves the counter is path-agnostic and catches the hallucinated-variant pattern observed in live testing.
• test_load_resource_failures_isolated_per_invocation — failures from invocation A do not escalate the first attempt in invocation B even when sharing the same session state dict.
• test_load_resource_counter_uses_temp_prefix — every key written by the guard starts with temp: so it is trimmed from the persisted event delta and never reaches durable storage.
• test_load_resource_first_missing_returns_soft_error — first RESOURCE_NOT_FOUND in an invocation returns the unchanged soft error code and message.

Verification:

• All 85 tests pass (81 pre-existing + 4 updated guard tests + 1 new soft-error coverage test), 0 regressions.
• pyink --check clean on both modified files.
• isort --check-only clean on both modified files.
• mypy src/google/adk/tools/skill_toolset.py reports the same 17 pre-existing errors as main; zero new errors introduced.

Backwards compatibility

• The first-failure behavior is unchanged: same RESOURCE_NOT_FOUND error code, same error string. Existing callers see no difference.
• The new RESOURCE_NOT_FOUND_FATAL code is purely additive.
• The new state key uses the temp: prefix and is guaranteed not to leak into persisted session storage.